/*
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

/*
 *
 *
 *
 *
 *
 * Written by Doug Lea with assistance from members of JCP JSR-166
 * Expert Group and released to the public domain, as explained at
 * http://creativecommons.org/publicdomain/zero/1.0/
 */

package java.util.concurrent;

import java.util.Collection;
import java.util.List;

/**
 * ExecutorService接口是Executor接口的扩展，它添加了用于管理任务执行的额外方法。
 * 提供了更高级别的任务调度和管理功能，比如可以等待任务完成，关闭服务等。
 */
public interface ExecutorService extends Executor {

    /**
     * 关闭，不再接受新的任务提交，并且等待已经提交的任务执行完成。
     * 该方法是异步的，调用后立即返回，不会等待所有任务执行完成。
     */
    void shutdown();

    /**
     * 关闭，并且尝试取消正在执行的任务。
     * 与shutdown()方法不同的是，该方法会尝试停止正在执行的任务，适合需要紧急停止所有任务的场景。
     * @return 返回是否成功关闭ExecutorService
     */
    List<Runnable> shutdownNow();

    /**
     * 检查ExecutorService是否已经关闭。
     * @return 如果ExecutorService已经关闭，则返回true；否则返回false。
     */
    boolean isShutdown();


    boolean isTerminated();


    boolean awaitTermination(long timeout, TimeUnit unit)
        throws InterruptedException;











    // 提交一个Callable任务给ExecutorService执行，并返回一个Future对象

    /*
     * submit方法的执行过程
     * 1、提交一个任务后，submit方法首先会检查线程池是否有空闲线程可用来执行该任务
     * 2、如果有，  submit方法会把任务直接提交给一个空闲线程执行，并返回一个表示该任务执行状态的Future对象；
     * 3、如果没有，submit方法会把该任务添加到线程池的等待队列中等待执行，并返回一个表示该任务排队状态的Future对象
     * 4、当线程池的某个线程空闲时，会从等待队列中取出头部的任务并交给该线程执行
     *
     * submit方法的异常处理
     *  提交一个Callable任务时，任务可能会抛出异常，
     *  如果我们没有对异常进行捕获处理，那么任务所在的线程将会退出，从而导致该线程无法执行其他任务
     *  为了避免这种情况的发生，我们可以通过捕获Future.get方法抛出的ExecutionException异常来获取任务执行过程中抛出的异常，并进行处理。
     */





    /**
     * 提交一个Callable任务给ExecutorService执行，并返回一个Future对象，
     * 通过该Future对象可以获取任务执行的结果或者取消任务。
     * @param task 要执行的Callable任务
     * @return 返回一个Future对象，用于获取任务执行的结果或者取消任务
     */
    <T> Future<T> submit(Callable<T> task);

    /**
     * 提交一个Runnable任务给ExecutorService执行，并返回一个Future对象，
     * 该Future对象的get方法总是返回null。
     * @param task 要执行的Runnable任务
     * @return 返回一个Future对象，用于获取任务执行的结果或者取消任务
     */
    Future<?> submit(Runnable task);

    /**
     * 提交一个Runnable任务和它执行的结果给ExecutorService执行，并返回一个Future对象，
     * 通过该Future对象可以获取任务执行的结果或者取消任务。
     * @param task 要执行的Runnable任务
     * @param result 任务执行的结果
     * @param <T> 任务结果的类型
     * @return 返回一个Future对象，用于获取任务执行的结果或者取消任务
     */
    <T> Future<T> submit(Runnable task, T result);




    <T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks)
        throws InterruptedException;


    <T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks,
                                  long timeout, TimeUnit unit)
        throws InterruptedException;




    /**
     * 执行给定的任务，返回一个成功完成的结果（即没有抛出异常），
     * 如果其中一个任务执行结束(或者抛了一个异常)，其他 Callable 将被取消。
     * 如果在此操作正在进行中修改了给定的集合，则此方法的结果是未定义的。
     * @param tasks 任务的收集
     * @param <T> 其中一个任务返回的结果
     * @return 其中一个任务返回的结果
     * @throws InterruptedException  如果在等待时中断
     * @throws ExecutionException    如果没有任务成功完成
     */
    <T> T invokeAny(Collection<? extends Callable<T>> tasks)
        throws InterruptedException, ExecutionException;


    /**
     * 执行给定的任务，返回一个已经成功完成的结果（即，不抛出异常），如果有的话在给定的超时之前过去。
     * 如果其中一个任务执行结束(或者抛了一个异常)，其他 Callable 将被取消。
     * 如果在此操作正在进行中修改了给定的集合，则此方法的结果是未定义的
     * @param tasks    任务的收集
     * @param timeout  等待的最长时间
     * @param unit     超时参数的时间单位
     * @return 其中一个任务返回的结果
     * @param <T>  从任务返回的值的类型
     * @throws InterruptedException  等待时中断
     * @throws ExecutionException 如果没有任务成功完成
     * @throws TimeoutException 如果在任务成功完成之前已经过了给定的超时
     */
    <T> T invokeAny(Collection<? extends Callable<T>> tasks,
                    long timeout, TimeUnit unit)
        throws InterruptedException, ExecutionException, TimeoutException;
}
